
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>7. Usage considerations &#8212; PSA Crypto API 1.1.0 documentation</title>
    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.1.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="8. Library management reference" href="../api/library/index.html" />
    <link rel="prev" title="6. Implementation considerations" href="implementation.html" />
   
  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head>
  <body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="usage-considerations">
<span id="id1"></span><h1>7. Usage considerations</h1>
<div class="section" id="security-recommendations">
<h2>7.1. Security recommendations</h2>
<div class="section" id="always-check-for-errors">
<h3>7.1.1. Always check for errors</h3>
<p>Most functions in this API can return errors. All functions that can fail have
the return type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>. A few functions cannot fail, and thus, return
<code class="docutils literal"><span class="pre">void</span></code> or some other type.</p>
<p>If an error occurs, unless otherwise specified, the content of the output
parameters is undefined and must not be used.</p>
<p>Some common causes of errors include:</p>
<ul class="simple">
<li>In implementations where the keys are stored and processed in a separate
environment from the application, all functions that need to access the
cryptography processing environment might fail due to an error in the
communication between the two environments.</li>
<li>If an algorithm is implemented with a hardware accelerator, which is
logically separate from the application processor, the accelerator might fail,
even when the application processor keeps running normally.</li>
<li>Most functions might fail due to a lack of resources. However, some
implementations guarantee that certain functions always have sufficient
memory.</li>
<li>All functions that access persistent keys might fail due to a storage failure.</li>
<li>All functions that require randomness might fail due to a lack of entropy.
Implementations are encouraged to seed the random generator with sufficient
entropy during the execution of <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. However, some security
standards require periodic reseeding from a hardware random generator, which
can fail.</li>
</ul>
</div>
<div class="section" id="shared-memory-and-concurrency">
<h3>7.1.2. Shared memory and concurrency</h3>
<p>Some environments allow applications to be multithreaded, while others do not.
In some environments, applications can share memory with a different security
context. In environments with multithreaded applications or shared memory,
applications must be written carefully to avoid data corruption or leakage. This
specification requires the application to obey certain constraints.</p>
<p>In general, this API allows either one writer or any number of simultaneous
readers, on any given object. In other words, if two or more calls access the
same object concurrently, then the behavior is only well-defined if all the
calls are only reading from the object and do not modify it. Read accesses
include reading memory by input parameters and reading keystore content by using
a key. For more details, refer to <a class="reference internal" href="conventions.html#concurrency"><span class="secref">Concurrent calls</span></a>.</p>
<p>If an application shares memory with another security context, it can pass
shared memory blocks as input buffers or output buffers, but not as non-buffer
parameters. For more details, refer to <a class="reference internal" href="conventions.html#stability-of-parameters"><span class="secref">Stability of parameters</span></a>.</p>
</div>
<div class="section" id="cleaning-up-after-use">
<h3>7.1.3. Cleaning up after use</h3>
<p>To minimize impact if the system is compromised, it is recommended that
applications wipe all sensitive data from memory when it is no longer used. That
way, only data that is currently in use can be leaked, and past data is not
compromised.</p>
<p>Wiping sensitive data includes:</p>
<ul class="simple">
<li>Clearing temporary buffers in the stack or on the heap.</li>
<li>Aborting operations if they will not be finished.</li>
<li>Destroying keys that are no longer used.</li>
</ul>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3>
IHI 0086<br/>
Non-confidential<br/>
Version 1.1.0
<span style="color: red; font-weight: bold;"></span>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li>
<li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">7. Usage considerations</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#security-recommendations">7.1. Security recommendations</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#always-check-for-errors">7.1.1. Always check for errors</a></li>
<li class="toctree-l3"><a class="reference internal" href="#shared-memory-and-concurrency">7.1.2. Shared memory and concurrency</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cleaning-up-after-use">7.1.3. Cleaning up after use</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
<li class="toctree-l1"><a class="reference internal" href="../appendix/encodings.html">Algorithm and key type encoding</a></li>
<li class="toctree-l1"><a class="reference internal" href="../appendix/specdef_values.html">Example macro implementations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../appendix/sra.html">Security Risk Assessment</a></li>
<li class="toctree-l1"><a class="reference internal" href="../appendix/history.html">Changes to the API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; 2018-2022, Arm Limited or its affiliates. All rights reserved.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
      
    </div>

    

    
  </body>
</html>